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Web APIs use HTTP to communicate between client and server. Plumber endpoints contain R code that is executed in response to an Plumber APIs can be run programmatically 
HTTP HTTP request. Incoming requests pass through a set of mechanisms from within an R session. 
= before a response is returned to the client. eee es Path to API definition 
: | aux 
ae < _‘Tesponse SO 
client server 






plumb ("plumber.R") %>3 eas 
Filters can forward requests (after potentially mutating them), throw ee eee! 


errors, or return a response without forwarding the request. Filters 
are defined similarly to endpoints using the @filter [name] This runs the API on the host machine supported by the current R 
session. 


tag. By default, filters apply to all endpoints. Endpoints can opt out 
B. PY e P P P IDE INTEGRATION 


of filters using the @preempt tag. 
O ~ Ox) = ~ = Æ@ Goto file/function x -|k Publish API to 
PARSER = = 2 RStudio Connect 
® > R Script TEN al 


Parsers determine how Plumber parses the incoming request body. Create naw | | > RunAPL~ G~ = 
By default Plumber parses the request body as JavaScript Object Plumber API 
Notation (JSON). Other parsers, including custom parsers, are 
identified using the @parser [parser name] tag. All 
registered parsers can be viewed with registered parsers(). 


ENDPOINT 


HTTP is built around a request and a response. A client makes a 
request to a server, which handles the request and provides a 
response. Requests and responses are specially formatted text 
containing details and data about the exchange between client and 
server. 

REQUEST 


Ma PAVA rA Curi -vý http: DEPIM Org ger" 
P CETE SOOT Ta A 
a E wae O Ore 
Headers 
Cu ail User Agents curly 7, 55.1 


#> Accept: */* 
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# Request Body 
Message body 














Run API in 


current R session 











Documentation 


Plumber APIs automatically generate an OpenAPI specification file. 
Endpoints define the R code that is executed in response to This specification file can be interpreted to generate a dynamic 





















RESPONSE incoming requests. These endpoints correspond to HTTP methods user-interface for the API. The default interface is generated via 
and respond to incoming requests that match the defined method. Swagger 
Status code i GET /echo Echo back the input 
METHODS A 
Reason phrase ; : 
Pa UTP I T IOO OK e @get - request a resource e @head - no request body te Seeley Parameters 








#< Connection: keep-alive 
CHB Date: Thu, 02 Aug 2018 18:22:22 GMT 
# 


# Response Body 
Message body 


e @post - send data in body e @options - describe options 
e @put - store / update data e @patch - partial changes 
e @delete -delete resource e Quse - use all methods 






Name Description 


Parameter details msg Edit parameters 
< The message to echo 







string 





(query) 











Hello 
Plumber: Build APIs with R cay | nlc 
| Serializers determine how Plumber returns results to the client. By 
Plumber uses special comments to turn any arbitrary R code into API default Plumber serializes the R object returned into JavaScript Execute 
endpoints. The example below defines a function that takes the msg Object Notation (JSON). Other serializers, including custom 
argument and returns it embedded in additional text. serializers, are identified using the @serializer curl sa tags SR esponses 
[serializer name] tag. All registered serializers can be ~ 
AMAR @ decorators viewed with registered serializers(). a ' — 
comments Waen n er define API = a -X GET "http://127.0.0.1:5762/echo?msg=Hello" -H "accept: 
begin with #* characteristics 3 
#* @apiTitle Plumber Example API ee st ee cy 
cer e 
ee ee eee p #* @filter log Interact with the API 
CROT DAC e inpu . , , , , , , 
a noo ee ae Forward iine zeasirre useR Aen Once the API is running, it can be interacted with using any HTTP 
ICO R= omy A aie ete request a F 7 client. Note that using httr requires using a separate R session 


/<path> is used to 


HTTP Method eras age RAOLA define the location 


Endpoint 
msg = pasted ( description Pe Convert request body to uppercase (resp <- httr::GET("localhost:5762/echo?msg=Hello") ) 
"The message 1s: rA msg, T) #> Response [http://localhost:5762/echo?msg=Hello] 


) a P 22 Opt out of #> Date: 2018-08-07 20:06 
' Parser argi parser json the log filter o 
} EX @post /uppercase. #> C Ili POL a 
Gaiam  Cserializer json #> oe Pa le ee 
function(reg, res) { Endpoint path ieee commences Fe eee 5), 
ic eae are ’ _ 
oupper (req$body) ie inscili a ion mes aceon s a ew renin ileal 


} 
Studio 
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} from the one serving the API. 





of the endpoint 





Programmatic Plumber 


Tidy Plumber 

Plumber is exceptionally customizable. In addition to using special 
comments to create APIs, APIs can be created entirely programatically. 
This exposes additional features and functionality. Plumber has a 
convenient “tidy” interface that allows API routers to be built piece by 
piece. The following example is part of a standard plumber .R file. 


oie S) Use @plumber tag 
#* @polumber 


Function that accepts and 





function(pr) { 





ioe as modifies a plumber router 
pr get (path = "/echo", 
handler = function(msg = "") { 
list(msg = paste0 ( 
“Tidy” functions Aa eek EN i 
for building out a 
Plumber API ) ) 
}) a> 
pr get (path -~ “plot, 
handler = function () { 


Eon =" rnr OO) 
hist (rand) 
by 


serializer = serializer png()) %>% 
joie Soe Pate sith, 
handler = function(a, b) { 


as.mumeric(a) + as. numeric (bh) 


m) 
} 


OpenAPI 

Plumber automatically creates an OpenAPI specification file based on 
Plumber comments. This file can be further modified using 

pr set api spec () with either a function that modifies the 
existing specification or a path toa .yaml or . json specification file. 


library (plumber) 


#* @param msg The message to echo 
#* @get /echo 
fünction(mog ~ "T 
Weri 
msg = pasted ( 
"The message is: 


ae) 


oS Shey 
) 


Function that receives 


and modifies the existing 
specification 


#* (@plumber 
function(pr) { 
pr 6>% 
Pre cel api spec function (spec) | 
specSpaths[["/echo"]]SgetSsummary <- 
TECNO Dack viele. ahigyobne ! 


spec. 
}) Return the updated 
j specification 


By default, Swagger is used to interpret the OpenAPI specification file 
and generate the user interface for the API. Other interpreters can be 
used to adjust the look and feel of the user interface via 

pr set docs(). 


E studio 





Advanced Plumber 


REQUEST and RESPONSE 


Plumber provides access to special req and res objects that can 
be passed to Plumber functions. These objects provide access to the 
request submitted by the client and the response that will be sent to 
the client. Each object has several components, the most helpful of 
which are outlined below: 


Name Example Description 


req 


The Plumber router 


lumber: :pr 
aa Ea processing the request 


reqsSpr 


Typically the same as 


req$body list(a=1) gui 
Th d bod 
reqsSargsBody list(a=1) e parsed body 
output 
The values of the path 
req$argsPath list(c=3) a j 
arguments 
req$argsQuer E E The parsed output trom 
as a req$QUERY STRING 
A ts list(cook = "a") A list of cookies 
A uO "GET" The method used for 
Í p the HTTP request 
TE The path of the 
req$PATH_INFO / 


incoming HTTP request 


All of the HTTP headers 
sent with the request 


reqSHTTP * 


"HTTP USER AGENT" 


The raw() contents of 


reqesbodyRaw 
qes x the request body 


charToRaw("a=1") 


HTTP headers to 
include in the response 


list(header = 


resSheaders n h 
abc ) 


setHeader("foo", 


‘ y Sets an HTTP header 
bar") 


resSsetHeader ( ) 


Sets an HTTP cookie on 
the client 


setCookie("foo", 


res$setCookie() "bar" ) 


Removes an HI TP 


resSremoveCookie 
cookie 


removeCookie("f0o" ) 


resSbody "{\"a\":[1]}" Serialized output 


The response HTTP 


resSstatus 200 
status code 


Alistof status, 


res$toResponse( ) headers, and body 


toResponse( ) 
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ASYNC PLUMBER 


Plumber supports asynchronous execution via 
the future R package. This pattern allows 
Plumber to concurrently process multiple 
requests. 





library (plumber) 


tüture -Plan (“multi ession") , 
Set the execution 


plan 





#* @get /slow 
function() { 

Ones cs: Urr eorom se 

slow cal- () 





Ei 
) Slow calculation 


} 


MOUNTING ROUTERS 
Plumber routers can be combined by mounting routers into other 
routers. This can be beneficial when building routers that involve 
several different endpoints and you want to break each component 
out into a separate router. These separate routers can even be 
separate files loaded using plumb ( ). 





Create an initial 


library (plumber) router 


routre KS Sie) eos, 
pr get ("/ foo", function ( 


TOOS 


#* @plumber 
function(pr) { 
BiR 
fone mount O Jeyewe T route 





into another 


) 
Mount one router 
) 


} 


In the above example, the final route is /bar/foo. 


RUNNING EXAMPLES 


Some packages, like the Plumber package itself, may include 
example Plumber APIs. Available APIs can be viewed using 
available apis(). These example APIs can be run with 
plumb api() combined with pr run(). 





Identify the 
1; 1 package name and 
ibrary (plumber) API name 
(Sluis eis Ueeiclssicie voi linmlets ie: 
name = "Ol-append", 
edit = TRUE) —32% 





jhe cn Optionally open the 


file for editing 


Run the example 
API 


Deploying Plumber APIs 


Once Plumber APIs have been > RunAPl ~ “@-~ 
developed, they often need to be 

deployed somewhere to be useful. 
Plumber APIs can be deployed in a 
variety of different ways. One of the 
easiest way to deploy Plumber APIs is using RStudio Connect, 


which supports push button publishing trom the RStudio IDE. 


“S- Publish API... 


Manage Accounts... 
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